﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

	<head>
		<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
		<title>Abp Session</title>
		<link type="text/css" rel="stylesheet" href="bootstrap.min.css" />
		<style type="text/css">
		</style>
	</head>

	<body>

		<div class="document-contents">

			<h3 id="DocIntroduction">Introduction</h3>
			<p>ASP.NET Boilerplate provides <strong>IAbpSession</strong> 
			interface to obtain current user and tenant <strong>without</strong> 
			using ASP.NET's Session. IAbpSession is also fully integrated and used by other structures in ASP.NET 
Boilerplate (<a href="Setting-Management.html">setting</a> system and 
			<a href="Authorization.html">authorization</a> system for instance).</p>

			<h3 id="DocInjectingSession">Injecting Session</h3>
			<p>IAbpSession is generally <strong>
					<a href="/Pages/Documents/Dependency-Injection#DocPropertyInjection">
property injected</a>
				</strong> to needed classes unless it's not possible to 
work without session informations. If we use property injection, we can use
				<strong>NullAbpSession.Instance</strong> as default value as shown below:</p>
			<pre lang="cs">public class MyClass : ITransientDependency
{
    public IAbpSession AbpSession { get; set; }

    public MyClass()
    {
        AbpSession = NullAbpSession.Instance;
    }

    public void MyMethod()
    {
        var currentUserId = AbpSession.UserId;
        //...
    }
}</pre>
			<p>Since authentication/authorization is an application layer task, it's adviced to <strong>use 
IAbpSession in application layer and upper layers</strong> (we don't use it in 
domain layer normally). <strong>ApplicationService</strong>, <strong>
AbpController,</strong> <strong>AbpApiController</strong> and some other base classes has
				<strong>AbpSession</strong> already injected. So, you can directly use 
AbpSession property in an application service method for instance.</p>
			<h3 id="DocUsingSession">Session Properties</h3>
			<p>AbpSession defines a few key properties:</p>
			<ul>
				<li>
					<strong>UserId</strong>: Id of the current user or null if there 
	is no current user. It can not be null if the calling code is authorized.</li>
				<li>
					<strong>TenantId</strong>: Id of the current tenant or null if there is 
	no current tenant (in case of user has not logged in or he is a host user).</li>
				<li>
					<strong>ImpersonatorUserId</strong>: Id of the impersonator user if 
	current session is impersonated by another user. It's null if this is not an 
	impersonated login.</li>
				<li>
					<strong>ImpersonatorTenantId</strong>: Id of the impersonator user's 
	tenant, if current session is impersonated by another user. It's null if 
	this is not an impersonated login.</li>
				<li>
					<strong>MultiTenancySide</strong>: It may be Host or Tenant.</li>
			</ul>
			<p>UserId and TenantId is <strong>nullable</strong>. There is also non-nullable
				<strong>GetUserId()</strong> and <strong>GetTenantId()</strong> methods. If 
you're sure there is a current user, you can call GetUserId(). If current user 
is null, this method throws exception. GetTenantId() is also similar.</p>
			<p>Impersonator properties are not common as other properties and generally used 
for <a href="/Pages/Documents/Audit-Logging">audit logging</a> purposes.</p>

			<div class="bs-callout bs-callout-warning">
				<p><strong>ClaimsAbpSession</strong></p>
				<p>ClaimsAbpSession is the <strong>default implementation</strong> 
				of IAbpSession interface. It gets session properties (except MultiTenancySide, 
				it's calculated) from claims of current user's princical. For a 
				cookie based form authentication, it gets from cookies. Thus, 
				it' well integrated to ASP.NET's authentication mechanism.</p>
			</div>

		<h3>Overriding Current Session Values</h3>
		<p>In some specific cases, you may need to change/override session 
		values for a limited scope. In such cases, you can use IAbpSession.Use 
		method as shown below:</p>
		<pre lang="cs">public class MyService
{
    private readonly IAbpSession _session;

    public MyService(IAbpSession session)
    {
        _session = session;
    }

    public void Test()
    {
<strong>        using (_session.Use(42, null))
        {
            var tenantId = _session.TenantId; //42
            var userId = _session.UserId; //null
        }
</strong>    }
}</pre>
		<p>Use method returns an IDisposable and it <strong>must be disposed</strong>. 
		Once the return value is disposed, Session values are <strong>
		automatically restored</strong> the to previous values.</p>
			<div class="bs-callout bs-callout-warning">
				<h4>Warning!</h4>
		<p>Always use it in a using block as shown above. Otherwise, you may get 
		unexpected session values. You can have nested Use blocks and they will 
		work as you expect.</p>
			</div>
		<h3>User Identifier</h3>
		<p>You can use <strong>.ToUserIdentifier()</strong> extension method to create a 
		UserIdentifier object from IAbpSession. Since UserIdentifier is used in 
		most API, this will simplify to create a UserIdentifier object for the current 
		user.</p>
		
</div>


	</body>

</html>
